Describing Folders

As of Mac OS 8 and later, your application can add folders to the System Folder—or nest folders within other folders—and use the Folder Manager to find the folders. Once a folder (and any folders that it is nested within) is described in a folder descriptor, your application can use the Folder Manager to find the folder no matter where it is located.

The Folder Manager provides the following functions for describing folders:

AddFolderDescriptor copies the supplied information into a new folder descriptor entry in the system folder list.
GetFolderDescriptor obtains the folder descriptor information for the specified folder type from the global descriptor list.
GetFolderName obtains the name of the specified folder.
GetFolderTypes obtains the folder types contained in the global descriptor list.
IdentifyFolder obtains the folder type for the specified folder.
InvalidateFolderDescriptorCache invalidates any prior FindFolder results for the specified folder.
RemoveFolderDescriptor deletes the specified folder descriptor entry from the system folder list.

AddFolderDescriptor

Copies the supplied information into a new folder descriptor entry in the system folder list.



 
pascal OSErr AddFolderDescriptor (

                     FolderType foldType,

                     FolderDescFlags flags,

                     FolderClass foldClass,

                     FolderLocation foldLocation,

                     OSType badgeSignature,

                     OSType badgeType,

                     ConstStr63Param name,

                     Boolean replaceFlag);

foldType: Pass a constant identifying the type of the folder you wish the Folder Manager to be able to find. See Folder Type Constants .
flags: Set these flags to indicate whether a folder is created during startup, if the folder name is locked, and if the folder is created invisible; see Folder Descriptor Flag Constants .
foldClass: Pass the class of the folder which you wish the Folder Manager to be able to find. The folder class determines how the foldLocation parameter is interpreted. See Folder Descriptor Class Constants for a discussion of relative and special folder classes.
foldLocation: For a relative folder, specify the folder type of the parent folder of the target. For a special folder, specify the location of the folder; see Folder Descriptor Location Constants .
badgeSignature: Reserved. Pass 0.
badgeType: Reserved. Pass 0.
name: A string specifying the name of the desired folder. For relative folders, this is the exact name of the desired folder. For special folders, the actual target folder may have a different name than the name specified in the folder descriptor. For example, the System Folder is often given a different name, but it can still be located with FindFolder .
replaceFlag: Pass a Boolean value indicating whether you wish to replace a folder descriptor that already exists for the specified folder type. If true , it replaces the folder descriptor for the specified folder type. If false , it does not replace the folder descriptor for the specified folder type.
function result: A result code; see Folder Manager Result Codes . The result code duplicateFolderDescErr indicates that a folder descriptor is already installed with the specified folder type and replaceFlag is false.

DISCUSSION

TheAddFolderDescriptor function copies the supplied information into a new descriptor entry in the system folder list. You need to provide folder descriptors for each folder you wish the Folder Manager to be able to find via the function FindFolder . For example, a child folder located in a parent folder needs to have a descriptor created both for it and its parent folder, so that the child can be found.

VERSION NOTES

Supported under Mac OS 8 and later.

GetFolderDescriptor

Obtains the folder descriptor information for the specified folder type from the global descriptor list.



 
pascal OSErr GetFolderDescriptor (

                     FolderType foldType,

                     Size descSize,

                     FolderDesc *foldDesc);

foldType: Pass a constant identifying the type of the folder for which you wish to get descriptor information. See Folder Type Constants .
descSize: Pass the size (in bytes) of the folder descriptor structure for which a pointer is passed in the foldDesc parameter. This value is needed in order to determine the version of the structure being used.
foldDesc: Pass a pointer to a folder descriptor structure. On return, the folder descriptor structure contains information from the global descriptor list for the specified folder type.
function result: A result code; see Folder Manager Result Codes .

VERSION NOTES

Supported under Mac OS 8 and later.

GetFolderName

Obtains the name of the specified folder.



 
pascal OSErr GetFolderName (

                     short vRefNum,

                     OSType foldType,

                     short *foundVRefNum,

                     Str63 name);

vRefNum: Pass the volume reference number (or the constant kOnSystemDisk for the startup disk) of the volume containing the folder for which you wish the name to be identified.
foldType: Pass a constant identifying the type of the folder for which you wish the name to be identified. See Folder Type Constants .
foundVRefNum: A pointer to a value of type short . On return, the value is set to the volume reference number for the volume containing the folder specified in the foldType parameter.
name: On return, a string containing the title of the folder specified in the foldType and vRefNum parameters.
function result: A result code; see Folder Manager Result Codes .

DISCUSSION

The GetFolderName function obtains the name of the folder in the folder descriptor, not the name of the folder on the disk. The names may differ for a few special folders such as the System Folder. For relative folders, however, the actual name is always returned. You typically do not need to call this function.

VERSION NOTES

Supported under Mac OS 8 and later.

GetFolderTypes

Obtains the folder types contained in the global descriptor list.



 
pascal OSErr GetFolderTypes (

                     UInt32 requestedTypeCount,

                     UInt32 *totalTypeCount,

                     FolderType *theTypes);

requestedTypeCount: Pass the number of FolderType values that can fit in the buffer pointed to by the theTypes parameter; see Folder Type Constants .
totalTypeCount: Pass a pointer to an unsigned 32-bit integer value. On return, the value is set to the total number of FolderType values in the list. The totalTypeCount parameter may produce a value that is larger or smaller than that of the requestedTypeCount parameter. If totalTypeCount is equal to or smaller than the value passed in for requestedTypeCount and the value produced by the theTypes parameter is non-nil , then all folder types were returned to the caller.
theTypes: Pass a pointer to an array of FolderType values; see Folder Type Constants . On return, the array contains the folder types for the installed descriptors. You can step through the array and call GetFolderDescriptor for each folder type. Pass nil if you only want to know the number of descriptors installed in the system's global list, rather than the actual folder types of those descriptors.
function result: A result code; see Folder Manager Result Codes .

VERSION NOTES

Supported under Mac OS 8 and later.

IdentifyFolder

Obtains the folder type for the specified folder.



 
pascal OSErr IdentifyFolder (

                     short vRefNum,

                     long dirID,

                     FolderType *foldType);

vRefNum: Pass the volume reference number (or the constant kOnSystemDisk for the startup disk) of the volume containing the folder whose type you wish to identify.
dirID: Pass the directory ID number for the folder whose type you wish to identify.
foldType: Pass a pointer to a value of type FolderType . On return, the value is set to the folder type of the folder with the specified vRefNum and dirID parameters; see Folder Type Constants for descriptions of possible values.
function result: A result code; see Folder Manager Result Codes .

DISCUSSION

The folder type is identified for the folder specified by the vRefNum and dirID parameters, if such a folder exists. Note that IdentifyFolder may take several seconds to complete. Note also that if there are multiple folder descriptors that map to an individual folder, IdentifyFolder returns the folder type of only the first matching descriptor that it finds.

VERSION NOTES

Supported under Mac OS 8 and later.

InvalidateFolderDescriptorCache

Invalidates any prior FindFolder results for the specified folder.



 
pascal OSErr InvalidateFolderDescriptorCache (

                     short vRefNum,

                     long dirID);

vRefNum: Pass the volume reference number (or the constant kOnSystemDisk for the startup disk) of the volume containing the folder for which you wish the descriptor cache to be invalidated. Pass 0 to completely invalidate all folder cache information.
dirID: Pass the directory ID number for the folder for which you wish the descriptor cache to be invalidated. Pass 0 to invalidate the cache for all folders on the specified disk.
function result: A result code; see Folder Manager Result Codes .

DISCUSSION

The InvalidateFolderDescriptorCache function searches to see if there is currently a cache of results from FindFolder calls on the specified folder. If so, it invalidates the cache from the previous calls to the FindFolder function in order to force the Folder Manager to reexamine the disk when FindFolder is called again on the specified directory ID or volume reference number.

You should not normally need to call InvalidateFolderDescriptorCache .

VERSION NOTES

Supported under Mac OS 8 and later.

RemoveFolderDescriptor

Deletes the specified folder descriptor entry from the system folder list.



 
pascal OSErr RemoveFolderDescriptor (FolderType foldType);

foldType: Pass a constant identifying the type of the folder for which you wish to remove a descriptor. See Folder Type Constants .
function result: A result code; see Folder Manager Result Codes .

DISCUSSION

Once a folder descriptor has been removed, the function FindFolder will no longer be able to locate the folder type.

VERSION NOTES

Supported under Mac OS 8 and later.